reveal-md 中文文档

发表于 阅读次数：

reveal-md 中文文档

将Markdown文件转换为漂亮的reveal.js演示文稿。

安装

1
npm install -g reveal-md

使用方法

1
reveal-md slides.md

这将启动一个本地服务器，并在默认浏览器中打开任何Markdown文件作为reveal.js演示文稿。

Docker

您可以使用Docker在不需要在您的机器上安装Node.js的情况下运行此工具。运行公共Docker镜像，
将您的Markdown幻灯片作为一个卷提供。以下是一些示例：

1
2
docker run --rm -p 1948:1948 -v <path-to-your-slides>:/slides webpronl/reveal-md:latest
docker run --rm -p 1948:1948 -v <path-to-your-slides>:/slides webpronl/reveal-md:latest --help

服务现在正在 http://localhost:1948 上运行。

要在容器中启用实时重新加载，还应该映射端口35729。

1
docker run --rm -p 1948:1948 -p 35729:35729 -v <path-to-your-slides>:/slides webpronl/reveal-md:latest /slides --watch

特性

Markdown

reveal.js 的 Markdown 功能非常棒，并且具有易于配置的语法来分离幻灯片。使用三个
破折号被两个空行(\n---\n)包围。例如：

1
2
3
4
5
6
7
8
9
10
11
12
# Title

- Point 1
- Point 2

---

## Second slide

> Best quote ever.

Note: speaker notes FTW!

代码段

语法高亮
1
2
3
```js
console.log('你好，世界！');
```
高亮显示某些行

您可以选择高亮显示一行、多行或同时高亮显示。

1
2
3
4
5
6
7
8
9
```python [1|3-6]
n = 0
while n < 10:
  if n % 2 == 0:
    print(f"{n} 是偶数")
  else:
    print(f"{n} 是奇数")
  n += 1
```

主题

覆盖主题（默认为 black）：

1
reveal-md slides.md --theme solarized

请查看可用的主题。

使用自定义主题覆盖reveal主题。在这个例子中，文件位于 ./theme/my-custom.css：

1
reveal-md slides.md --theme theme/my-custom.css

使用远程主题覆盖reveal主题（使用rawgit.com，因为URL必须允许跨站点访问）：

1
reveal-md slides.md --theme https://rawgit.com/puzzle/pitc-revealjs-theme/master/theme/puzzle.css

高亮主题

覆盖高亮主题（默认为zenburn）:

1
reveal-md slides.md --highlight-theme github

查看可用主题。

自定义幻灯片分隔符

覆盖幻灯片分隔符（默认为\n---\n）：

1
reveal-md slides.md --separator "^\n\n\n"

覆盖垂直/嵌套幻灯片分隔符（默认为\n----\n）:

1
reveal-md slides.md --vertical-separator "^\n\n"

自定义幻灯片属性

使用reveal.js幻灯片属性功能来添加HTML属性，例如自定义背景。或者，为特定的幻灯片添加HTML id 属性，并使用CSS样式设置。

示例：将第二张幻灯片设置为具有PNG图像作为背景：

1
2
3
4
5
6
7
8
9
10
11
# slide1

This slide has no background image.

---

<!-- .slide: data-background="./image1.png" -->

# slide2

This one does!

reveal-md选项

在Markdown文件的根目录下，定义类似于命令行选项的reveal-md.json文件中的选项。它们将被自动识别。示例：

1
2
3
4
{
  "separator": "^\n\n\n",
  "verticalSeparator": "^\n\n"
}

Reveal.js选项

在Markdown文件的根目录下定义Reveal.js的选项37，并将其保存在一个名为reveal.json的文件中。
它们将被自动识别。示例：

1
2
3
4
{
  "controls": true,
  "progress": true
}

演讲者注释

通过以Note:开头的行来使用演讲者注释功能。

YAML前置元数据

使用YAML前置元数据设置特定于演示文稿的Markdown（和reveal.js）选项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
title: Foobar
separator: <!--s-->
verticalSeparator: <!--v-->
theme: solarized
revealOptions:
  transition: 'fade'
---

Foo

Note: test note

<!--s-->

# Bar

<!--v-->

实时重新加载

使用 -w 选项，对 markdown 文件进行更改将会触发浏览器重新加载，从而在不需要用户手动重新加载浏览器的情况下显示更改后的演示文稿。

1
reveal-md slides.md -w

自定义脚本

将自定义脚本注入到页面中：

1
reveal-md slides.md --scripts script.js,another-script.js
  • 不要使用绝对文件路径，文件应该在相邻或下级文件夹中。
  • 允许使用绝对URL。

自定义CSS

将自定义CSS注入到页面中：

1
reveal-md slides.md --css style.css,another-style.css
  • 不要使用绝对文件路径，文件应该在相邻或下级文件夹中。
  • 允许使用绝对URL。

自定义Favicon

如果包含Markdown文件的目录中存在一个favicon.ico文件，则会自动将其用作Favicon，而不是默认的Favicon。

预处理Markdown

可以通过--preprocessor（或-P）选项给reveal-md提供一个Markdown预处理脚本。这对于预处理Markdown非常有用。
可以在不深入了解Markdown解析器的内部结构的情况下对文档格式进行自定义调整。

例如，要使标题自动创建新的幻灯片，可以使用以下脚本preproc.js：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// headings trigger a new slide
// headings with a caret (e.g., '##^ foo`) trigger a new vertical slide
module.exports = (markdown, options) => {
  return new Promise((resolve, reject) => {
    return resolve(
      markdown
        .split('\n')
        .map((line, index) => {
          if (!/^#/.test(line) || index === 0) return line;
          const is_vertical = /#\^/.test(line);
          return (is_vertical ? '\n----\n\n' : '\n---\n\n') + line.replace('#^', '#');
        })
        .join('\n')
    );
  });
};

并像这样使用它

1
reveal-md --preprocessor preproc.js slides.md

导出为PDF

有至少两种方法可以将一个幻灯片导出为PDF文件。

1. 使用Puppeteer

从提供的Markdown文件创建一个（可打印的）PDF文件：

1
reveal-md slides.md --print slides.pdf

PDF是使用Puppeteer生成的。或者，在命令行或浏览器中将?print-pdf添加到URL中（确保删除#/或#/1哈希值）。然后，使用浏览器（而不是本地的）打印对话框打印幻灯片。在Chrome中似乎可以工作。

默认情况下，纸张大小设置为与您的reveal.json文件中的选项相匹配，如果没有则回退到默认值960x700。
像素。要覆盖这种行为，您可以通过命令行选项--print-size传递自定义的尺寸或格式。

1
2
3
reveal-md slides.md --print slides.pdf --print-size 1024x768   # in pixels when no unit is given
reveal-md slides.md --print slides.pdf --print-size 210x297mm  # valid units are: px, in, cm, mm
reveal-md slides.md --print slides.pdf --print-size A4         # valid formats are: A0-6, Letter, Legal, Tabloid, Ledger

如果出现错误，请尝试以下操作：

  • 分析调试输出，例如 DEBUG=reveal-md reveal-md slides.md --print
  • 查看Puppeteer参数（puppeteer-launch-args和puppeteer-chromium-executable）的帮助文档 reveal-md help
  • 使用Docker和DeckTape：

2. 使用Docker和DeckTape

当在Docker容器中运行reveal-md时，第一种打印方法目前不起作用，因此建议使用Docker和DeckTape进行打印。
您可以使用DeckTape来打印幻灯片。使用DeckTape可能还可以解决内置打印方法输出的问题。

要使用DeckTape Docker映像在本地主机上运行的reveal-md幻灯片创建PDF文件，请使用以下命令：

1
docker run --rm -t --net=host -v $OUTPUT_DIR:/slides astefanutti/decktape $URL $OUTPUT_FILENAME

替换这些变量：

  • $OUTPUT_DIR 是您想要保存PDF的文件夹。
  • $OUTPUT_FILENAME 是PDF的文件名。
  • $URL 是在浏览器中访问演示文稿的网址（不包括?print-pdf后缀）。如果您没有在Docker中运行reveal-md，您需要将localhost替换为您计算机的IP地址。

有关导出选项的完整列表，请参阅DeckTape github，或者在Docker容器中使用-h标志运行。

静态网站

这将把提供的Markdown文件导出为一个独立的HTML网站，包括脚本和样式表。文件将保存在传递给 --static 参数的目录中（默认为 ./_static）:

1
reveal-md slides.md --static _site

这将连同幻灯片一起复制图像。使用--static-dirs将其他静态资产的目录复制到目标目录中。使用逗号分隔的列表复制多个目录。

1
reveal-md slides.md --static --static-dirs=assets

提供一个目录将生成一个独立的概述页面，其中包含指向演示文稿的链接（类似于directory listing）：

1
reveal-md dir/ --static

默认情况下，生成的网站中包含所有子目录中的所有 *.md 文件。您可以使用 --glob 提供自定义的 glob模式，只从匹配的文件中生成幻灯片：

1
reveal-md dir/ --static --glob '**/slides.md'

可以使用--absolute-url和--featured-slide参数来生成OpenGraph元数据，从而在某些社交网站上共享幻灯片链接时实现更吸引人的呈现效果。

1
reveal-md slides.md --static _site --absolute-url https://example.com --featured-slide 5

禁用自动打开浏览器

要禁用自动打开浏览器：

1
reveal-md slides.md --disable-auto-open

目录列表

显示Markdown文件的（递归）目录列表：

1
reveal-md dir/

显示当前目录中Markdown文件的目录列表：

1
reveal-md

自定义端口

覆盖端口 (默认: 1948):

1
reveal-md slides.md --port 8888

自定义模板

覆盖 reveal.js 的 HTML 模板（默认模板）：

1
reveal-md slides.md --template my-reveal-template.html

覆盖列表的HTML模板（默认模板）：

1
reveal-md slides.md --listing-template my-listing-template.html

脚本、预处理器和插件

相关项目和替代方案

  • Slides 是一个用于创建、展示和共享幻灯片的平台。
  • Sandstorm Hacker Slides 是一个将 Ace Editor 和 RevealJS 结合在一起的简单应用程序。
  • Tools 是 Reveal.js 的插件、工具和硬件部分的工具集。
  • Org-Reveal 将 Org-mode 内容导出为 Reveal.js HTML 演示文稿。
  • DeckTape 是一个用于 HTML5 演示框架的高质量 PDF 导出工具。
  • GitPitch 可以从托管在 Git 仓库中的 PITCHME.md 文件生成幻灯片。

关于 reveal-md 的文章

感谢

非常感谢所有的贡献者！

许可证

MIT